19.8 Asking Multiple Y-or-N Questions

When you have a series of similar questions to ask, such as “Do you want to save this buffer?” for each buffer in turn, you should use map-y-or-n-p to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at once.

Function: map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area

This function asks the user a series of questions, reading a single-character answer in the echo area for each one.

The value of list specifies the objects to ask questions about. It should be either a list of objects or a generator function. If it is a function, it should expect no arguments, and should return either the next object to ask about, or nil, meaning to stop asking questions.

The argument prompter specifies how to ask each question. If prompter is a string, the question text is computed like this:

(format prompter object)

where object is the next object to ask about (as obtained from list).

If not a string, prompter should be a function of one argument (the next object to ask about) and should return the question text. If the value is a string, that is the question to ask the user. The function can also return t, meaning do act on this object (and don’t ask the user), or nil, meaning ignore this object (and don’t ask the user).

The argument actor says how to act on the answers that the user gives. It should be a function of one argument, and it is called with each object that the user says yes for. Its argument is always an object obtained from list.

If the argument help is given, it should be a list of this form:

(singular plural action)

where singular is a string containing a singular noun that describes the objects conceptually being acted on, plural is the corresponding plural noun, and action is a transitive verb describing what actor does.

If you don’t specify help, the default is ("object" "objects" "act on").

Each time a question is asked, the user may enter y, Y, or SPC to act on that object; n, N, or DEL to skip that object; ! to act on all following objects; ESC or q to exit (skip all following objects); . (period) to act on the current object and then exit; or C-h to get help. These are the same answers that query-replace accepts. The keymap query-replace-map defines their meaning for map-y-or-n-p as well as for query-replace; see Search and Replace.

You can use action-alist to specify additional possible answers and what they mean. It is an alist of elements of the form (char function help), each of which defines one additional answer. In this element, char is a character (the answer); function is a function of one argument (an object from list); help is a string.

When the user responds with char, map-y-or-n-p calls function. If it returns non-nil, the object is considered acted upon, and map-y-or-n-p advances to the next object in list. If it returns nil, the prompt is repeated for the same object.

Normally, map-y-or-n-p binds cursor-in-echo-area while prompting. But if no-cursor-in-echo-area is non-nil, it does not do that.

If map-y-or-n-p is called in a command that was invoked using the mouse—more precisely, if last-nonmenu-event (see Command Loop Info) is either nil or a list—then it uses a dialog box or pop-up menu to ask the question. In this case, it does not use keyboard input or the echo area. You can force use either of the mouse or of keyboard input by binding last-nonmenu-event to a suitable value around the call.

The return value of map-y-or-n-p is the number of objects acted on.